#Node API 兼容性与导入说明

Scripting 在 JavaScriptCore 上提供 Node 兼容层。本文列出实际注册的内置模块、可用 API 子集与限制。App Shell 中的 node 命令也使用这个环境，不会启动桌面版 Node 可执行文件。process.version / process.versions.node 是兼容基线，不代表完整支持对应版本。小组件、键盘、Safari、隔离 vm context 的能力可能不同；本文链接的网络示例面向 App 普通脚本。

#应该从哪里导入

已注册内置模块的 "net" 与 "node:net" 指向同一模块。子路径需要单独注册：支持 "stream" 不代表支持 "stream/web"。ES import 和 CommonJS require 都可使用，但模块经过宿主转译后采用 CommonJS 风格加载，不是完整的 Node 原生 ESM 加载器。入口脚本支持顶层 await，任意被 require 的模块不支持模块顶层 await。

下方链接的新 API 页中，每个代码块都是独立的 App 普通脚本，导入写在顶部，异步示例会等待工作结束。过早调用 Script.exit() 会关闭脚本自有资源并取消定时器。

#只用内置模块的完整示例

无需安装包、启动服务器或准备文件。短暂延时后输出 hello 及其 SHA-256 十六进制摘要。

import { Buffer } from "node:buffer"
import { createHash } from "node:crypto"
import { setTimeout as sleep } from "node:timers/promises"

// process 和 console 是全局对象，不从 scripting 导入。
const message = Buffer.from("hello", "utf8")
await sleep(10)
console.log(message.toString("utf8"))
console.log(createHash("sha256").update(message.toString("utf8")).digest("hex"))
console.log(process.version, process.platform, process.cwd())

#有实际功能的模块与 API 子集

“子集”表示下列操作可用，同时遵循本页及详细文档的限制，不代表完整兼容最新版 Node。表中的模块名均可加 node: 前缀。

大写全局 Crypto 使用 Scripting Data，小写全局 crypto 是 WebCrypto。HKDF 与显式 ChaCha20-Poly1305 扩展应通过 crypto.subtle / crypto.chacha20Poly1305 使用，或从 node:crypto 导入 webcrypto；不要据此推断存在 createCipheriv("chacha20-poly1305", ...) 或 Node hkdfSync。见 HKDF/ChaCha、Curve25519。

Bonjour 是 Scripting 全局 API，不是 Node 内置模块，见发布/浏览/解析完整示例。web-globals 是内部提供全局对象的辅助资源，脚本直接使用已文档化的全局 API 即可。

#能加载但主要用于兼容探测的占位模块

这些模块可被导入，让包的可选依赖路径有机会继续执行；能导入不代表有真实功能。有些调用会抛错，有些只返回空值或不产生实际效果。

dgram、inspector、repl、wasi 在加载时拒绝。其他未注册的 Node 名称和内部模块也不支持，包括 domain、sys、trace_events、inspector/promises、assert/strict、path/posix、path/win32、stream/web。解析器保留了名称或编辑器出现补全，都不能当作已有实现。

#第三方 npm 包如何判断能否运行

可通过“工具 → npm 包”或在 App Shell 执行 npm install <真实包名> 安装。解析、格式化、校验和数据处理等纯 JavaScript 包，在依赖都使用上表实际能力时通常适合。兼容性取决于包版本、依赖树和实际执行路径，没有通用的 npm 全版本白名单。仅 import/require 成功不能证明网络、子进程或原生路径可用。

采用一个包前：

1. 核对直接和间接依赖使用的 Node 模块，尤其是占位表。真正依赖 AsyncLocalStorage 上下文、DNS 查询、Worker 或子进程的路径需要替代实现。
2. 优先选择纯 JS 分发。.node 原生扩展、下载的可执行文件、浏览器自动化引擎和系统构建工具无法通过兼容层运行。
3. 依赖安装的 preinstall/install/postinstall/prepare 脚本会跳过，optionalDependencies 不自动安装；安装成功可能仍缺少可选原生功能。
4. 实际执行目标操作，检查响应/结果、错误处理和清理；不要只验证 require 成功、版本号匹配或 typeof fn 为 function。
5. 继续遵循网络/文件授权和 iOS 前后台限制；第三方包不会获得宿主脚本没有的能力。

完整调用签名请以 App 随附 TypeScript 声明与详细 API 页为准。本文描述 Scripting 的实际实现，不承诺桌面 Node 文档中的全部接口。